home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / nspr / prshma.h < prev    next >
C/C++ Source or Header  |  2006-04-20  |  9KB  |  272 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is the Netscape Portable Runtime (NSPR).
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1999-2000
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38. /*
  39. ** prshma.h -- NSPR Anonymous Shared Memory
  40. **
  41. ** NSPR provides an anonymous shared memory based on NSPR's PRFileMap
  42. ** type. The anonymous file-mapped shared memory provides an inheritable
  43. ** shared memory, as in: the child process inherits the shared memory.
  44. ** Compare the file-mapped anonymous shared memory to to a named shared
  45. ** memory described in prshm.h. The intent is to provide a shared
  46. ** memory that is accessable only by parent and child processes. ...
  47. ** It's a security thing.
  48. ** 
  49. ** Depending on the underlying platform, the file-mapped shared memory
  50. ** may be backed by a file. ... surprise! ... On some platforms, no
  51. ** real file backs the shared memory. On platforms where the shared
  52. ** memory is backed by a file, the file's name in the filesystem is
  53. ** visible to other processes for only the duration of the creation of
  54. ** the file, hopefully a very short time. This restricts processess
  55. ** that do not inherit the shared memory from opening the file and
  56. ** reading or writing its contents. Further, when all processes
  57. ** using an anonymous shared memory terminate, the backing file is
  58. ** deleted. ... If you are not paranoid, you're not paying attention.
  59. ** 
  60. ** The file-mapped shared memory requires a protocol for the parent
  61. ** process and child process to share the memory. NSPR provides two
  62. ** protocols. Use one or the other; don't mix and match.
  63. ** 
  64. ** In the first protocol, the job of passing the inheritable shared
  65. ** memory is done via helper-functions with PR_CreateProcess(). In the
  66. ** second protocol, the parent process is responsible for creating the
  67. ** child process; the parent and child are mutually responsible for
  68. ** passing a FileMap string. NSPR provides helper functions for
  69. ** extracting data from the PRFileMap object. ... See the examples
  70. ** below.
  71. ** 
  72. ** Both sides should adhere strictly to the protocol for proper
  73. ** operation. The pseudo-code below shows the use of a file-mapped
  74. ** shared memory by a parent and child processes. In the examples, the
  75. ** server creates the file-mapped shared memory, the client attaches to
  76. ** it.
  77. **
  78. ** First protocol.
  79. ** Server:
  80. **
  81. **   fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); 
  82. **   addr = PR_MemMap(fm); 
  83. **   attr = PR_NewProcessAttr();
  84. **   PR_ProcessAttrSetInheritableFileMap( attr, fm, shmname );
  85. **   PR_CreateProcess(Client); 
  86. **   PR_DestroyProcessAttr(attr);
  87. **   ... yadda ...
  88. **   PR_MemUnmap( addr );
  89. **   PR_CloseFileMap(fm);
  90. **
  91. **
  92. ** Client: 
  93. **   ... started by server via PR_CreateProcess()
  94. **   fm = PR_GetInheritedFileMap( shmname );
  95. **   addr = PR_MemMap(fm);
  96. **   ... yadda ...
  97. **   PR_MemUnmap(addr);
  98. **   PR_CloseFileMap(fm);
  99. **
  100. **
  101. ** Second Protocol:
  102. ** Server:
  103. **
  104. **   fm = PR_OpenAnonFileMap(dirName, size, FilemapProt); 
  105. **   fmstring = PR_ExportFileMapAsString( fm );
  106. **   addr = PR_MemMap(fm); 
  107. **    ... application specific technique to pass fmstring to child
  108. **    ... yadda ... Server uses his own magic to create child
  109. **   PR_MemUnmap( addr );
  110. **   PR_CloseFileMap(fm);
  111. **
  112. **
  113. ** Client: 
  114. **   ... started by server via his own magic
  115. **   ... application specific technique to find fmstring from parent
  116. **   fm = PR_ImportFileMapFromString( fmstring )
  117. **   addr = PR_MemMap(fm);
  118. **   ... yadda ...
  119. **   PR_MemUnmap(addr);
  120. **   PR_CloseFileMap(fm);
  121. **
  122. **
  123. ** lth. 2-Jul-1999.
  124. **
  125. ** Note: The second protocol was requested by NelsonB (7/1999); this is
  126. ** to accomodate servers which already create their own child processes
  127. ** using platform native methods.
  128. ** 
  129. */
  130.  
  131. #ifndef prshma_h___
  132. #define prshma_h___
  133.  
  134. #include "prtypes.h"
  135. #include "prio.h"
  136. #include "prproces.h"
  137.  
  138. PR_BEGIN_EXTERN_C
  139.  
  140. /*
  141. ** PR_OpenAnonFileMap() -- Creates an anonymous file-mapped shared memory
  142. **
  143. ** Description:
  144. ** PR_OpenAnonFileMap() creates an anonymous shared memory. If the
  145. ** shared memory already exists, a handle is returned to that shared
  146. ** memory object.
  147. **
  148. ** On Unix platforms, PR_OpenAnonFileMap() uses 'dirName' as a
  149. ** directory name, without the trailing '/', to contain the anonymous
  150. ** file. A filename is generated for the name.
  151. **
  152. ** On Windows platforms, dirName is ignored.
  153. **
  154. ** Inputs:
  155. **   dirName -- A directory name to contain the anonymous file.
  156. **   size -- The size of the shared memory
  157. **   prot -- How the shared memory is mapped. See prio.h
  158. **   
  159. ** Outputs:
  160. **   PRFileMap *
  161. **
  162. ** Returns:
  163. **   Pointer to PRFileMap or NULL on error.
  164. **
  165. */
  166. NSPR_API( PRFileMap *)
  167. PR_OpenAnonFileMap(
  168.     const char *dirName,
  169.     PRSize      size, 
  170.     PRFileMapProtect prot
  171. );  
  172.  
  173. /*
  174. ** PR_ProcessAttrSetInheritableFileMap() -- Prepare FileMap for export  
  175. **   to my children processes via PR_CreateProcess()
  176. **
  177. ** Description:
  178. ** PR_ProcessAttrSetInheritableFileMap() connects the PRFileMap to
  179. ** PRProcessAttr with shmname. A subsequent call to PR_CreateProcess()
  180. ** makes the PRFileMap importable by the child process.
  181. **
  182. ** Inputs:
  183. **   attr -- PRProcessAttr, used to pass data to PR_CreateProcess()
  184. **   fm -- PRFileMap structure to be passed to the child process
  185. **   shmname -- The name for the PRFileMap; used by child.
  186. **
  187. ** Outputs:
  188. **   PRFileMap *
  189. **
  190. ** Returns:
  191. **   PRStatus
  192. **
  193. */
  194. NSPR_API(PRStatus) 
  195. PR_ProcessAttrSetInheritableFileMap( 
  196.     PRProcessAttr   *attr,
  197.     PRFileMap       *fm, 
  198.     const char      *shmname
  199. );
  200.  
  201. /*
  202. ** PR_GetInheritedFileMap() -- Import a PRFileMap previously exported
  203. **   by my parent process via PR_CreateProcess()
  204. **
  205. ** Description:
  206. ** PR_GetInheritedFileMap() retrieves a PRFileMap object exported from
  207. ** its parent process via PR_CreateProcess().
  208. **
  209. ** Inputs:
  210. **    shmname -- The name provided to PR_ProcessAttrSetInheritableFileMap()
  211. ** 
  212. ** Outputs:
  213. **   PRFileMap *
  214. **
  215. ** Returns:
  216. **   PRFileMap pointer or NULL.
  217. **
  218. */
  219. NSPR_API( PRFileMap *)
  220. PR_GetInheritedFileMap( 
  221.     const char *shmname 
  222. );
  223.  
  224. /*
  225. ** PR_ExportFileMapAsString() -- Creates a string identifying a PRFileMap
  226. **
  227. ** Description:
  228. ** Creates an identifier, as a string, from a PRFileMap object
  229. ** previously created with PR_OpenAnonFileMap().
  230. **
  231. ** Inputs:
  232. **   fm -- PRFileMap pointer to be represented as a string.
  233. **   bufsize -- sizeof(buf)
  234. **   buf -- a buffer of length PR_FILEMAP_STRING_BUFSIZE
  235. **
  236. ** Outputs:
  237. **   buf contains the stringized PRFileMap identifier
  238. **
  239. ** Returns:
  240. **   PRStatus
  241. **
  242. */
  243. NSPR_API( PRStatus )
  244. PR_ExportFileMapAsString( 
  245.     PRFileMap *fm,
  246.     PRSize    bufsize,
  247.     char      *buf
  248. );
  249. #define PR_FILEMAP_STRING_BUFSIZE 128
  250.  
  251. /*
  252. ** PR_ImportFileMapFromString() -- Creates a PRFileMap from the identifying string
  253. **
  254. ** Description:
  255. ** PR_ImportFileMapFromString() creates a PRFileMap object from a
  256. ** string previously created by PR_ExportFileMapAsString().
  257. **
  258. ** Inputs:
  259. **   fmstring -- string created by PR_ExportFileMapAsString()
  260. **
  261. ** Returns:
  262. **   PRFileMap pointer or NULL.
  263. **
  264. */
  265. NSPR_API( PRFileMap * )
  266. PR_ImportFileMapFromString( 
  267.     const char *fmstring
  268. );
  269.  
  270. PR_END_EXTERN_C
  271. #endif /* prshma_h___ */
  272.